{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img src=\"../common/rfsoc_book_banner.jpg\" alt=\"University of Strathclyde\" align=\"left\">"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Notebook Set F\n",
    "\n",
    "---\n",
    "\n",
    "## 02 - RFSoC Frequency Planner\n",
    "This notebook presents an RFSoC frequency planner tool developed entirely using Python. Plotly and ipywidget libraries are used to provide dynamic visualisation and control. The Frequency Planner tool is derived from the [original RFSoC frequency planner](https://www.xilinx.com/publications/products/tools/zynq-ultrascale-plus-rfsoc-frequency-planner-rev1p7.xlsx.zip).\n",
    "\n",
    "## Table of Contents\n",
    "* [1. Introduction](#introduction)\n",
    "* [2. Running the Application](#running-the-application)\n",
    "* [3. How to Frequency Plan](#how-to)\n",
    "* [4. Conclusion](#conclusion)\n",
    "\n",
    "## References\n",
    "* [1] - [Xilinx, Inc, \"USP RF Data Converter: LogiCORE IP Product Guide\", PG269, v2.3, June 2020](https://www.xilinx.com/support/documentation/ip_documentation/usp_rf_data_converter/v2_3/pg269-rf-data-converter.pdf)\n",
    "* [2] - [Xilinx, Inc, \"RFSoC Frequency Planner\", rev1p7, March, 2020](https://www.xilinx.com/publications/products/tools/zynq-ultrascale-plus-rfsoc-frequency-planner-rev1p7.xlsx.zip)\n",
    "* [3] - [Xilinx, Inc., “Understanding Key Parameters for RF-Sampling Data Converters”, WP509, v1.0, February 2019.](https://www.xilinx.com/support/documentation/white_papers/wp509-rfsampling-data-converters.pdf)\n",
    "\n",
    "## Revision\n",
    "* **v1.0** | 12/01/23 | *First Revision*\n",
    "\n",
    "---\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 1. Introduction <a class=\"anchor\" id=\"introduction\"></a>\n",
    "This notebook provides a frequency planning tool for Xilinx Zynq UltraScale+ RFSoC. The frequency planner is based on the original tool [2] that runs in Microsoft Excel. This Python-based version has been developed to permit a tighter integration with other PYNQ-based materials for RFSoC, and to explore the pedagogical potential of Python and Jupyter in the context of RF systems. \n",
    "\n",
    "The frequency planning tool is also available as a standalone web application that can be found at the following link: [rfsoc-frequency-planner.herokuapp.com](https://rfsoc-frequency-planner.herokuapp.com/)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 2. Running the Application <a class=\"anchor\" id=\"running-the-application\"></a>\n",
    "The frequency planning tool is organised into five tabs: an information tab, and four different frequency planners for different components of the RFSoC. These are (from left to right): \n",
    "\n",
    "1. The Info tab contains general information regarding the tool, explains the terms used, and includes some parameter values that may be useful.\n",
    "2. Frequency planner for the Analogue to Digital Converter (ADC). \n",
    "3. Frequency planner for the Digital to Analogue Converter (DAC).\n",
    "4. Frequency planner for the Digital Downconverter (DDC). \n",
    "5. Frequency planner for the Digital Upconverter (DUC).   \n",
    "    \n",
    "Most of the parameters can be changed using the sliders, and the plots will update automatically. However, if you need exact values, these can be typed into the adjacent boxes (followed by a press of the Enter key). You can add and remove plot items by selecting them in the legend with your mouse, and also use the mouse to hover over any plot item to reveal its label.\n",
    "\n",
    "In the ADC and DAC tabs, if a spur is overlapping the main frequency band, it will be highlighted in red on both the plot and the legend.\n",
    "To start using the frequency planning tool, run the cell underneath (it may take a few seconds to load)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from rfsoc_freqplan.application import FrequencyPlannerApplication\n",
    "\n",
    "freqplan = FrequencyPlannerApplication()\n",
    "freqplan.tab"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 3. How to Frequency Plan <a class=\"anchor\" id=\"how-to\"></a>\n",
    "\n",
    "When setting parameters in the frequency planner, the ideal outcome is a plan where the signal band is not overlapped by any spurious bands. These bands arise from a few different sources:\n",
    "\n",
    "* Harmonics\n",
    "* Interleaving associated with the DAC and ADC\n",
    "* The Phase Locked Loop (PLL) reference clock used for the DAC and ADC\n",
    "* Interactions between the above \n",
    "    \n",
    "Some of the bands that appear in the frequency plan result from spectral imaging, or aliasing. In both cases this is dependent on the sampling frequency, which is set as a parameter in the frequency planner.\n",
    "\n",
    "By observing the positions of the spurious bands with respect to the signal band, parameters can be adjusted to minimise overlaps (as far as possible given other system constraints that might apply)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 4. Conclusion <a class=\"anchor\" id=\"conclusion\"></a>\n",
    "\n",
    "This notebook has briefly introduced a Python-based frequency planning tool, developed to complement PYNQ support for RFSoC, and which replicates the theoretical analysis of the original Xilinx frequency planning tool. \n",
    "\n",
    "We have noted that the frequency planning tools allows plans to be developed for four different aspects of RFSoC design: the ADC, DAC, DDC, and DUC. By using the interactive features of the frequency planner, you can experiment with frequency planning options to minimise the overlap of spurious bands onto the signal band. \n",
    "\n",
    "The next notebook explores a BPSK and QPSK radio transceiver design on RFSoC."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---\n",
    "\n",
    "[⬅️ Previous Notebook](01_frequency_planning.ipynb) || [Next Notebook 🚀](../notebook_G/01_rfsoc_radio_system.ipynb)\n",
    "\n",
    "Copyright © 2023 Strathclyde Academic Media\n",
    "\n",
    "---\n",
    "---"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.8.2"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}
